<c-layouts.with-sidebar>
    <h1 id="components">Usage Patterns</h1>

    <c-slot name="page_index">
        <c-index-link><a href="#components" class="no-underline">Components</a></c-index-link>
        <c-index-sublink><a href="#basics" class="no-underline text-opacity-70">Basics</a></c-index-sublink>
        <c-index-sublink><a href="#naming" class="no-underline">Naming</a></c-index-sublink>
        <c-index-sublink><a href="#subfolders" class="no-underline">Subfolders</a></c-index-sublink>
        <c-index-sublink><a href="#tag-syntax" class="no-underline">Tag Syntax</a></c-index-sublink>
        <c-index-sublink><a href="#index" class="no-underline">index.html</a></c-index-sublink>
        <c-index-sublink><a href="#attribute-proxying" class="no-underline">Attribute Proxying</a></c-index-sublink>
    </c-slot>

    <h3 id="basics">Basics</h3>
    <c-ul>
        <li>Cotton components should be placed in the <c-highlight>templates/cotton</c-highlight> folder ('cotton' path is <a href="{% url 'configuration' %}">configurable</a> using <code>COTTON_DIR</code>).</li>
        <li>The <code>templates</code> folder can be located in either an app-level or top-level project root folder.</li>
    </c-ul>

    <c-hr />

    <h3 id="naming">Naming</h3>
    <p>Cotton uses the following naming conventions:</p>
    <c-ul>
        <li>By default, component file names are in snake_case (<c-highlight>my_component.html</c-highlight>).
        <li>kebab-case filenames (<c-highlight>my-component.html</c-highlight>) can be enabled with <code>COTTON_SNAKE_CASED_NAMES = False</code> see <a href="{% url 'configuration' %}">configuration</a>.</li>
        <li>Components are included in templates using kebab-case name of the component: <code>{{ "<c-my-component />"|force_escape }}</code></li>
    </c-ul>

    <c-hr />

    <h3 id="subfolders">Subfolders</h3>

    <c-ul>
        <li>Components in subfolders can be called using dot notation to represent folder levels.</li>
        <li>A component in <c-highlight>sidebar/menu/link.html</c-highlight> would be included with <code>{{ "<c-sidebar.menu.link />"|force_escape }}</code></li>
    </c-ul>

    <c-hr />

    <h3 id="tag-syntax">Tag Syntax</h3>

    <p>Cotton components can be used with HTML-like syntax or native Django template tags.</p>

    <h4 class="text-lg font-semibold mt-6 mb-3">HTML-like Syntax</h4>

    <p>Cotton enables you to use html-like syntax to include your components. This tends to enhance productivity as editors and IDEs often provide autocompletion, auto closing and syntax highlighting of xml-like tags out of the box.</p>

    <c-snippet label="With content">{% cotton:verbatim %}{% verbatim %}
<c-button>
    Click me
</c-button>
    {% endverbatim %}{% endcotton:verbatim %}</c-snippet>

    <h4 class="text-lg font-semibold mt-6 mb-3">Native Template Tags</h4>

    <p>If you prefer using native template tags you can use Cotton's template tags.</p>

    <h5 class="font-semibold mt-4 mb-2">HTML Syntax</h5>
    <c-snippet label="HTML-like syntax" ignore-syntax-choice>{% cotton:verbatim %}{% verbatim %}
<c-button title="Click me">
    Click here
</c-button>
{% endverbatim %}{% endcotton:verbatim %}</c-snippet>

    <h5 class="font-semibold mt-4 mb-2">Native Syntax</h5>

    <c-snippet label="Native Django template syntax" ignore-syntax-choice>
{{ '{%'|force_escape }} cotton button title="Click me" {{ '%}'|force_escape }}
    Click here
{{ '{%'|force_escape }} endcotton {{ '%}'|force_escape }}
    </c-snippet>

    <h4 class="text-lg font-semibold mt-6 mb-3">Syntax Comparison</h4>

    <div class="overflow-x-auto">
        <table class="min-w-full border border-gray-200 dark:border-gray-700">
            <thead class="dark:bg-gray-800">
                <tr>
                    <th class="px-4 py-3 text-left text-sm font-semibold text-gray-700 dark:text-gray-300 uppercase tracking-wider border-b border-gray-200 dark:border-gray-700">Feature</th>
                    <th class="px-4 py-3 text-left text-sm font-semibold text-gray-700 dark:text-gray-300 uppercase tracking-wider border-b border-gray-200 dark:border-gray-700">HTML-like Syntax</th>
                    <th class="px-4 py-3 text-left text-sm font-semibold text-gray-700 dark:text-gray-300 uppercase tracking-wider border-b border-gray-200 dark:border-gray-700">Native Template Syntax</th>
                </tr>
            </thead>

            <tr class="border-b dark:border-b-gray-700 border-b-gray-200">
                <td class="px-4 py-3 text-sm text-gray-700 dark:text-gray-300">Component</td>
                <td class="px-4 py-3 text-sm font-mono text-gray-900 dark:text-gray-100"><code>&lt;c-button&gt;...&lt;/c-button&gt;</code></td>
                <td class="px-4 py-3 text-sm font-mono text-gray-900 dark:text-gray-100"><code>{{ '{%'|force_escape }} cotton button {{ '%}'|force_escape }}...{{ '{%'|force_escape }} endcotton {{ '%}'|force_escape }}</code></td>
            </tr>
            <tr class="border-b dark:border-b-gray-700 border-b-gray-200">
                <td class="px-4 py-3 text-sm text-gray-700 dark:text-gray-300">Self-closing Component</td>
                <td class="px-4 py-3 text-sm font-mono text-gray-900 dark:text-gray-100"><code>&lt;c-button /&gt;</code></td>
                <td class="px-4 py-3 text-sm font-mono text-gray-900 dark:text-gray-100"><code>{{ '{%'|force_escape }} cotton button / {{ '%}'|force_escape }}</code></td>
            </tr>
            <tr class="border-b dark:border-b-gray-700 border-b-gray-200">
                <td class="px-4 py-3 text-sm text-gray-700 dark:text-gray-300">Variables</td>
                <td class="px-4 py-3 text-sm font-mono text-gray-900 dark:text-gray-100"><code>&lt;c-vars title /&gt;</code></td>
                <td class="px-4 py-3 text-sm font-mono text-gray-900 dark:text-gray-100"><code>{{ '{%'|force_escape }} cotton:vars title {{ '%}'|force_escape }}</code></td>
            </tr>
            <tr class="border-b dark:border-b-gray-700 border-b-gray-200">
                <td class="px-4 py-3 text-sm text-gray-700 dark:text-gray-300">Named Slot</td>
                <td class="px-4 py-3 text-sm font-mono text-gray-900 dark:text-gray-100"><code>
                    <div>&lt;c-slot name="header"&gt;</div>
                    <div>...</div>
                    <div>&lt;/c-slot&gt;</div>
                </code>
                </td>
                <td class="px-4 py-3 text-sm font-mono text-gray-900 dark:text-gray-100"><code><div>{{ '{%'|force_escape }} cotton:slot header {{ '%}'|force_escape }}</div>
                    <div>...</div>
                    <div>{{ '{%'|force_escape }} endcotton:slot {{ '%}'|force_escape }}</div>
                </code></td>
            </tr>
        </table>
    </div>

    <c-hr />

    <h3 id="index">The index.html component</h3>

    <p>When your component has sub-components, you can define the default component of a folder by adding an <code>index.html</code>. This helps to keep your project structure tidy and reduce additional code in the template.</p>

    <c-snippet label="Project structure">
        {% cotton:verbatim %}{% verbatim %}
templates/
├── cotton/
│   ├── card/
│   │   ├── index.html
│   │   ├── header.html
        {% endverbatim %}{% endcotton:verbatim %}
    </c-snippet>

    <c-snippet label="Usage">
        {% cotton:verbatim %}{% verbatim %}
<c-card>
    <c-card.header>...</c-card.header>
</c-card>
        {% endverbatim %}{% endcotton:verbatim %}
    </c-snippet>

    <c-hr />

    <h3 id="attribute-proxying">Attribute Proxying Pattern</h3>

    <p>The <code>:attrs</code> dynamic attribute enables us to create wrapper components that proxy all their attributes to an inner component:</p>

    <c-snippet label="view.html">{% cotton:verbatim %}{% verbatim %}
<c-outer
    class="outer-class"
    :count="42"
    :enabled="False">
    Content passed to inner component
</c-outer>
    {% endcotton:verbatim %}{% endverbatim %}</c-snippet>

    <c-snippet label="cotton/outer.html">{% cotton:verbatim %}{% verbatim %}
<c-inner :attrs="attrs">{{ slot }}</c-inner>
    {% endcotton:verbatim %}{% endverbatim %}</c-snippet>

    <c-snippet label="cotton/inner.html">{% cotton:verbatim %}{% verbatim %}
{{ class }}     <!-- "outer-class" -->
{{ count }}     <!-- 42 -->
{{ enabled }}   <!-- False -->
{{ slot }}      <!-- Content passed to inner component -->
    {% endcotton:verbatim %}{% endverbatim %}</c-snippet>

    <p>The attributes are passed through to the inner component with their original types preserved (strings, numbers, booleans, lists, etc.), making this pattern ideal for creating higher-order components.</p>

    <p>This pattern is particularly useful for Django form fields, where you might create a component hierarchy that passes Django widget attributes through multiple layers while adding labels, error handling, and styling at each level.</p>

    <c-navigation>
        <c-slot name="prev">
            <a href="{% url 'components' %}">Components</a>
        </c-slot>
        <c-slot name="next">
            <a href="{% url 'form-fields' %}">Form Inputs</a>
        </c-slot>
    </c-navigation>

</c-layouts.with-sidebar>
